<?php
/**
 * In this File the class '\UF\IO\FileAccessException' is defined.
 *
 * @category   UniKap-Framework
 * @package    IO
 * @subpackage Exceptions
 * @author     Ulf -UniKado- Kadner <ulfikado@gmail.com>
 * @since      2014-03-29 16:17
 * @version    0.1
 */

namespace UF\IO
{

    /**
     * This exception should be used, if a error occours while accessing a file.
     *
     * @since  v0.1
     */
    class FileAccessException extends \UF\IO\Exception
    {

        # <editor-fold defaultstate="collapsed" desc="- - - -   C O N S T A N T S   - - - - - - - - - - - - - - - - - - - - - - - - - -">

        /**
         * Reading file access.
         *
         * @since  v0.1
         */
        const ACCESS_READ = 'read';

        /**
         * Writing file access.
         *
         * @since  v0.1
         */
        const ACCESS_WRITE = 'write';

        /**
         * Reading and writing file access.
         *
         * @since  v0.1
         */
        const ACCESS_READWRITE = 'read and write';

        /**
         * Create a new file
         *
         * @since  v0.1
         */
        const ACCESS_CREATE = 'create';

        /**
         * Delete a file.
         *
         * @since  v0.1
         */
        const ACCESS_DELETE = 'delete';

        # </editor-fold>

        # <editor-fold defaultstate="collapsed" desc="- - - -   P R I V A T E   F I E L D S   - - - - - - - - - - - - - - - - - - - - -">

        /**
         * @since  v0.1
         */
        private $access;

        # </editor-fold>

        # <editor-fold defaultstate="collapsed" desc="- - - >   C O N S T R U C T O R   - - - - - - - - - - - - - - - - - - - - - - - -">

        /**
         * Inits a new instance.
         *
         * @param  string     $file     The accessed file
         * @param  string     $access   see {@see \UF\IO\FileAccessException}::ACCESS_* constants
         * @param  string     $message  The optional error message
         * @param  int        $code     The optional error code (Defaults to \E_USER_ERROR)
         * @param  \Exception $previous A optional previous exception
         * @since  v0.1
         */
        public function __construct( $file, $access = self::ACCESS_READ,
            $message = null, $code=\E_USER_ERROR, \Exception $previous=null )
        {
            parent::__construct($file,
                \UF\_1( '_io', 'Could not %s file.', \UF\_( '_io', $access ) ) .
                ( empty ( $message ) ? '' : ( "\n" . $message ) ), $previous, $code );
            $this->access = $access;
        }

        # </editor-fold>

        # <editor-fold defaultstate="collapsed" desc="- - - -   P U B L I C   M E T H O D S   - - - - - - - - - - - - - - - - - - - - -">

        /**
         * Returns the access type (see {@see \UF\IO\FileAccessException}::ACCESS_* constants)
         *
         * @return string
         * @since  v0.1
         */
        public final function getAccessType()
        {
            return $this->access;
        }

        # </editor-fold>

        # <editor-fold defaultstate="collapsed" desc="- - - -   P U B L I C   S T A T I C   M E T H O D S   - - - - - - - - - - - - - -">

        /**
         * Inits a \UF\IO\FileAccessException for read mode.
         *
         * @param string $file The file where accessing fails.
         * @param string $message A optional error message
         * @return \UF\IO\FileAccessException
         * @since  v0.1
         */
        public static function Read( $file, $message = null )
        {
            return new \UF\IO\FileAccessException (
                $file, \UF\IO\FileAccessException::ACCESS_READ, $message );
        }

        /**
         * Inits a \UF\IO\FileAccessException for write mode.
         *
         * @param string $file The file where accessing fails.
         * @param string $message A optional error message
         * @return \UF\IO\FileAccessException
         * @since  v0.1
         */
        public static function Write( $file, $message = null )
        {
            return new \UF\IO\FileAccessException (
                $file, \UF\IO\FileAccessException::ACCESS_WRITE, $message );
        }

        # </editor-fold>

    }

}

